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DOCUMENTATION 



COURSE OUTLINE: 



Session 1 

• General principles of procedure writing 

♦ what is goal? purpose? 

♦ what is the best method for getting instructions across? 

standardized style: active voice, itrong verbs, subject/verb agreement, 
tense consistency, clear pronouns, clear time words 

♦ sequence/complete instructions - keep sequence consistent 

Students will write their own instructions for something they do at vork, 
e.g. getting into Word for Windows 

Session 2 

• principles of clear communication: clarity /audience/visuals 
assume audience is a raving bunch of neophytes - 

♦ particular attention on what questions the audience would need to have 
answered 

♦ generate student list of questions and concerns 

♦ visual- screen samples, diagrams 

• identification of system types/accounts/customer requests 

♦ generalizations? 

♦ standardized approaches? 

♦ client profiles - questions generated to standardize approach (what 
questions would you ask if you were asking about a new client or new 
system) 



DOCUMENT A TION 



Session 3 

• working with examples/fixing bad documentation 

♦ lack of clarity - ambiguous phrases, misplaced modifiers, unclear pronouns 

♦ incomplete steps - steps missing, steps not clear, sequence not given 

♦ poor profiles - fragments missing 

Students will work in pairs on worksheets and on a sample of bad documen- 
tation (short) written by us - then they will critique each other's work 

Session 4 

• good/bad documentation 

♦ generate list of comparison/contrast from students: what makes good/bad 
documentation? (clarity, user friendliness, consistent style, good and clear 
sequence, visuals) 

Students will work in pairs on exercises that apply these concepts - bad 
documentation sample from Michelle 

Session 5 

• students write their own documentation 



Session 6 

• Students critique each other's work and give feedback 
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DOCUMENTATION ♦ SESSION 1 



OBJECTIVES: 

In order to write clear documentation, at the end of this session students will be 
able to do the following: 

• identify goal and purpose 

• identify the best method for getting instructions across 

• use clear consistent sequence 

• use concise language 



TOPICS: 



goal and purpose 

clear sequence 

active vs. passive voice 

verb use 

modifiers 

pronouns 

clear instructions 

documentation pitfalls 



METHOD: 



class discussion 

individual work on worksheets 

pair work 
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DOCUMENTATION ♦ SESSION 1 



EVALUATION: 

At the end of this session, students will be competent in these areas: 

• determining the purpose and goal of documentation 

• writing in clear sequence 

• using concise language 

• generating simple instructions for a work task 

Coursework will be evaluated by students in both classes. Students' names will 
not appear on coursework. 

MATERIALS: 

• worksheets 

• student generated instructions 
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GOALS OF DOCUMENT A TION 



♦ to write effective documentation so that the user does not make mistakes 

♦ to write in the most efficient sequence 

♦ to write so that the document be read from the first word to the last. user 
must follow each step in order to complete the procedure. 

♦ to write in a clear, concise manner: using readily understood vocabulary and 
short sentences, taking into account the reading levels and experience of the 
users 

♦ to allow the product or system to shape the documentation 

♦ to have a flexible system that can easily be updated or adapted 
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GENERAL INSTRUCTIONS FOR WRITING INSTRUCTIONS 

When we write instructions, we must remember that our primary' goal is to 
instruct! To do that, we must use the following: 

♦ active voice 

♦ clear sequence 

♦ strong and clear verbs 

♦ consistent verb tenses 

♦ correctly placed modifiers 

♦ clear pronouns 

♦ clear time words or other directives 

♦ specific number amounts 



©Mercer County Community College 



Page 5 



CLEAR SEQUENCE 



Nothing is more frustrating than trying to read steps that are out of order. We have 
to use chronological order and be consistent in our sequence it we expect our 
audience to succeed. 

Look at these steps. What are they instructions for? What would the title be? Put 
the steps into the correct order. 



HOW TO 



insert paper into copier tray 



remove protective wrap from paper ream 



take paper tray out of copier 



press tray release button 



put paper tray back into position in copier 



hit the reset button 



make sure paper is placed correctly in tray (portrait, 
not landscape) 



press copy button to resume copying 
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ACTIVE VOICE VS. PASSIVE VOICE 



The Passive Voice is a structure that includes a form of the verb TO BE, and a past 
participle. The Active Voice is just what it says - more active, for it has a clear 
subject and a regular verb form. 

♦ Passive: The computer is turned on by the coordinator. 

♦ Active: The coordinator turns on the computer. 



The Passive voice is messy, wordy, and difficult to read through if you are looking 
for steps and directives. Look at this sentence and consider its problems: 

PASSIVE: 

The computer must be turned on, after it has been plugged in, and then the screen 
can be reached by pressing the F3 key, but not before the user number has been 
entered into the system by the user. 



The ACTIVE form is much shorter, easier to read and much easier to understand: 

After you plug in the computer and turn it on, enter your user number and press 
F3. 
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ACTIVE VOICE VS. PASSIVE VOICE 



Determine if these sentences are active or passive. If they are passive, make them 
active. 

1 . The manager opened the file drawer and took out the supplies. 



2. The system was designed by a Mobile executive, but it was redesigned by our 
company for its own use. 



3. After the enter button is pushed, the HELP screen should be seen by the user. 



4. The zip assignments are created for every new system and the addresses are 
contained in these files. 



5. We use the hard drive to store our shared files, but we use disks to store our 
personal accounts. 



6. The files on the hard Hrive are never duplicated, but they are often transferred 
between users. 
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STRONG AND CLEAR VERBS 



When we tell someone to do something, we want to make sure that the thing we 
want to tell them to do is clear and unambiguous. Got that? 

In other words, don't use verbs that are unclear or unprecise. 



Example 1 : Shut down the computer when you are not using it. 

What does shut down mean? Does it mean turn the system off? Or just turn that 
particular program off? Or does it mean return to a blank screen? 

To avoid such confusion, think of the specific action that you want the person to 
do. and tell him/her to do just that. 

Revision: Turn the computer off when you are not using it. 



Example 2: Exit this screen. 

What does exit mean? Move on to the next screen? Or move back to the previous 
one? And how do I exit anyway? Don't assume that your reader will know exactly 
what you mean or how to do it! 
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CONSISTENT VERB TENSES 



When you give directions, use commands when appropriate - that means y 
don't need to have a subject, just a verb. Commands are clear, concise, and easy 
interpret. 



Example: 



Sentence: You have to put the disk into the A-drive. 
Command: Put the disk into the A-drive. 



In general, avoid using the unnecessary third person -- that is, don't talk about what 
"the user" must do when in fact your audience is made up of users. Just use simple 
commands. 

If you do use subjects, make sure that your verb tenses are consistent -- that means 
all the same, or in similar time frames. 



Example: 

The computer has two drives: the C-drive and the A-drive. The A-drive 
will have a disk portal, but the C-drive won't have a portal. 

Note: "has" is the present tense, but "will have" is the future. There is no 
good reason to jump tenses, so stay in the present tense. 

Revision: 

The computer has two drives: the C-drive and the A-drive. The A-drive 
has a disk portal, but the C-drive does not have a portal. 
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CORRECTLY PLACED MODIFIERS 



Modifiers are words or phrases that give more information about the subject, verb, 
or object in a clause. A modifier dangles when the word it modifies is not actually 
in the sentence, or is misplaced when it seems to modify another part of the 
sentence than the writer intended. The result leads to confusion. 



Discuss the following sentences. How can you rewrite them to make them clearer? 
1 . Unless completely rewired, nobody should handle the faulty equipment. 



2. The report should be filed by the user in the folder. 



3. Upon entering the information into the system, the disk should be updated. 



4. We need to have a meeting to discuss the new system that will be put into 
effect by January 10th. 



5. Cracked and falling apart, Steve put the broken printer cover into a box. 
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CLEAR PRONOUNS 



♦ A pronoun is a word that replaces a noun. If you have more than one noun 
followed by a single pronoun, the reference can be unclear or confusing. 

Example: 

Keep the Quick Reference Card with the manual for easy reference and 
make sure it is updated regularly. 

Note: what does the "it" refer to? How can you rewrite this sentence to 
make your idea clear? 



♦ Pronouns must agree in number with the noun they refer to. Be especially 
careful if there are modifying phrases. 

Example: 

The bottle of aspirins is in the cabinet where they belong. 

Note: the bottle is singular, but they is plural. Why did this mistake 
occur? How can you fix it? 



♦ Pronouns that replace people must be correct in gender. Although "he" is 
stylistically correct, consider your audience and be gender sensitive. 

Example: 

After the coordinator writes down the information, he/she must enter it into 
the system. 
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CLEAR PRONOUNS 



♦ Indefinite pronouns are always singular, so be careful of possessives that refer 
to them. Indefinite pronouns are these: everyone, someone, no one, everybody, 
somebody, nobody, anyone, anybody 

Example: 

Everyone has the opportunity to correct their mistakes. 

Note: Everyone is singular, but their is plural How would you correct 
this error? 



18 



©Mercer County Community College 



Page 1 3 



CLEAR PRONOUNS 



Rewrite these sentences and correct the pronoun errors. 

1 . The grower must obtain the correct form and receipt and put it in an envelope 
with the other documents. 



2. Everyone who does documentation must be sure to enter their names into the 
svstem. 



3. The coordinators will generate reports, statements, and system scripts; the 
temporary data personnel will take them and use them to update the files. 



4. After reading the notebook of reports, the manager gave them to his assistant. 



5. The account coordinator takes time to check his accounts, record the 
information and enter them into the system. 
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CLEAR TIME WORDS AND SPECIFIC AMOUNTS 



♦ When you tell someone where to put something, how much to do something, 
how long to do something, or at what time to do something, you must give 
exact information. 

What's wrong with these sentences? 

Example I: 

Let the computer run for a little bit before you turn on the screen, and then hit 
the other button. 

How long is "a little bit" and which button am I to hit? 
These words are unclear. How could you be more precise? 

Example 2: 

Turn the nut a few times and let the glue dry for a while. 

1 low many times is a few times! 3 or 6 times? How long should the glue take 
to dry? 10 seconds or 10 minutes? Be precise! 

♦ When you give directions, make sure you specify exactly where and give 
reference points. 

Example I: 

The title field appears near the address field. 

What does near mean? Next to? To the left of? To the right of? Below? 
1 low can you make this directive more clear? 

Example 2: 

The account number appears in the corner. 

Which corner? How do we designate exact corners? ^ w 
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CLEAR TIME WORDS AND SPECIFIC AMOUNTS 



♦ Be sure to give complete directions in case of a "crisis." For example, if the 
user hits ENTER and is supposed to arrive at a certain screen, what should 
he/she do if a different screen appears? 

Example: 

When you press F5, the drive screen should appear. Then hit ENTER to 
change the drive reading. 

Problem: 

- Wh?:t happens if the user hits F5 but is then met with a blank screen, or a 
different screen? Be sure to tell the user how to get out of a potential crisis. 
Conditional statements (If . . . then . . .) work well on these occasions. 

In essence, don't ever lose your readers or leave them stranded - make sure 
they know not only what to expect, but what to do in case the unexpected 
occurs. 

Also, that "should" is not very comforting - take a firm stand and be confident 
that your directions will work! 



Revision: 



When you press F5, the drive screen appears. If the drive screen does not 
appear, then you are not ready to change drives. Press the ESCAPE key and 
this will take you back to the main menu. Press F5 again. If you do not get 
into the drive screen then, press CNTRL, ALT and DELETE together to reboot 
the system. This will take you back to step 3. 

Note: if you use the "if . . . then . . ." construction, make sure that it is not a 
backwards construction. 



Backwards: Press the CLEAR RESET key if you want to erase everything on 
the hard drive. 



Forwards: If you want to erase everything on the hard drive, press the CLEAR 
RESET key. 

. aj 
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DOCUMENT A TION PITFALLS 



Choose your words and phrases wisely. Remember, your goal is to communicate 
and instruct. Avoid these: 

/. Job Jargon 

Before: In the Information Center environment, the manager should utilize a 
prioritization ranking to facilitate equitable scheduling. 

After: In the Information Center, the manager ranks each job in order to 
produce a fair schedule. 

Before: If your configuration has sufficient RAM capacity, you may utilize the 
system's windowing capability. 

After: If your computer has enough memory, you can use the window feature. 



2. Too Many Words 

Before: In the event that you have a lack of knowledge regarding which drive 
you are working in, make use of the file manager component. 

After: If you don't know which drive you are working in, use the file manager. 

Before: Should it prove to be the case that you have some reservations regarding 
the forecasts, you have the option of employing alternate discount rates. 

After: I f you doubt the forecasts, try of >er discount rates. 



3. Vague and Incomplete Terminology 

Before: Get column heading revision permission from HCOL entry. 

After: If you need to change a column heading, enter HCOL. 

Before: Early manual design yields procedural usability benefits. 

After: Manuals will be easier to use if you write them as you develop the 
svstem. 
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INSTRUCTIONS 



Write a set of instructions for something that you do every day on the job. Make it 
a manageable task - no more than 10 steps - and be sure to apply the information 
given in these worksheets. Number the steps (to be very clear). 

When you are finished, we will use peer review to critique your work. 
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DOCUMENTATION ♦ SESSION 2 



OBJECTIVES: 

At the end of this session, students will be able to do the following: 

• analyze the audience 

• use visuals appropriately 

• present questions and answers 

• identify system types 

• use standard company procedures 

• generate client profiles 



TOPICS: 



• Lines of Communication 

• Audience Analysis 

• Visuals 

• Presentation Aids 

• Question and Answer Sessions 

• Company Procedures and Client Profiles 



METHODS: 



• class discussion 

• individual writing 

• pair work 



EVALUATION: 

At the end of this session, students will be competent in these areas: 

• identifying and categorizing system types 

• identifying audience needs 

• using visuals for instruction 

• writing client profiles 



MATERIALS: 



worksheets 

company document structure 
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A. Audience Identity: 



Who? 



Relationship to me? 



Knowledge about product? = 



Training/experience in the system? 
Intended use of document? 



Additional background information: 



Probable questions about product/system's 



Probable questions about document? 



B. Expectations 

Reason document originated: 



Importance of material to the audience: 
Intended effect: 
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VISUALS 




Sometimes it's easier to show something than it is to explain it in words. In that 
case, a visual is appropriate. 

♦ A visual is anything that shows readers what something looks like 
(illustration/diagram), how it works (flowchart), how information is compared 
(tables, charts, and graphs), or what they can expect on a screen (screen 
sample). 

♦ The visual should not be too complicated since what you are trying to do is 
make the concept easier for your readers! 

Note: don't use visuals indiscriminately for they can overwhelm the reader. Use 
them only when you feel they convey the message better than words 
would. 
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VISUALS 



Note to Instructor: 



Use job related diagrams according to individual company needs 
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PRESENTATION AIDS 



1) Never use a presentation aid before an audience until you have rehearsed 
with it. 

• Be sure it works! 

• Know how to set it up. 

• Try the visual out on videotape or with an objective observer 



2) Make sure the visual aid is a help rather than a hindrance to 
communication. 

• Keep aids simple, clear, and accurate 

• Don't use too many visuals; no more than 7 or 8 for a 1 5 minute 
presentation 

• Show only one key concept per visual 

• Be sure the visual conveys the idea better than speech alone could 

• Use pictures and graphics rather than text 

• Use contrast or color to emphasize or clarify main points, but don't overdo 
it 



3) Don't waste your audience's time with your presentation aids. 

• Be sure all necessary equipment is available and in place before you start 

• Be sure your visuals are in sequence before you start 

• Don't put away your equipment -- wait until your audience has left 



4) Project your voice more than normal 

• Remember that a listeners attention is divided between you and the visual 
(particularly if the room is darkened) 
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PRESENT A TION AIDS 



5) Don't stand between your listeners and the visual aid 

• Stand to one side (and vary the side) 

• Use a pointer 

6) Don't let the visual aid distract you 

• Face and talk to the audience, not to the aid 

• Don't interrupt your talk when you change slides or handle £ids 

• Use the aid to support your message; avoid modifying your message to 
support the aid 



7) Don't let the visual aid distract your audience 

• Don't show the aid until you are ready to use it 

• Handle the aid only when you are making a direct reference to it 

• When you're through with it, turn it off, remove it, or cover it 

• Don't pass objects around during the presentation; either show them to the 
group as a whole or display them afterwards 
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DESIGNING EFFECTIVE VISUAL AIDS 



An effective visual aid must . . . 



• Present an idea better than speech alone 

• Represent a key concept 

• Support only one major idea 

• Emphasize pictures or graphs rather than words 

• Restrict the use of text to a maximum of 6 words per line, and 10 
words per visual, with short phrases or key words rather than 
complete sentences 

• Use color or contrast to highlight important points 

• Represent facts accurately 

• Be neat, clear, uncluttered 

• Be appropriate to the audience, occasion, and message 

• Have impact! 
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QUESTION AND ANSWER SESSIONS 



9 9 9 9 



General Tips 



Anticipate the most likely questions and prepare suitable responses 



; Jot down statistics, dates, and other specific information 



Don't interrupt a question 



Repeat the question in your own words so that the audience can hear it and you 
hav * time to think about your answer 

If you are challenged, try "Yes, but . . ." to agree with a minor aspect of the 
question, but then go on to refute the questioner's position 
If the questioner persists, don't get into an argument - suggest discussion after 
the session 



9 c 



Spread questions around the room to avoid any one person dominating 



If questions aren't forthcoming, try posing a few yourself and answering them 
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HOW TO ANSWER QUESTIONS 



© Prepare: 

• anticipate 

• prepare 

• practice 



© Repeat the question: 



buy time 
let everyone hear it 

make sure you understand the question 
concentrate on the concept of the question 



© Maintain the same style 



• Don't suddenly shift into jargon or incompiehensible language 

• Don't become more nervous when you ad lib 

• Don't be afraid to say "I don't Know" - but try to get back to that 
person at a later date 



0 Involve the whole audience 

• Keep 20% of eye contact on the person who asked the question 

• and 80% to the rest of the audience 
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HOW TO ANSWER QUESTIONS 



0 Don't rate or judge the question 

• Don't say, "What a good question," or "Weren't you paying attention?" 

Neutralize negative questions 

• Turn negative comments or questions into positive answers 
e.g. "I think your product stinks!" 

"Oh, so you're asking about the quality of our product? Yes, 
independent testing shows that . . 



Bring the Q/A session to a close 

• Say, "Time for three more questions" or "We have a few more minutes" 

• Rephrase your summary 
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GETTING EVERYONE ON TRACK? 



If we want to get everyone on the same track in terms of documentation or make 
sure that we are all gathering and reporting similar information, then we all have o 
be asking the same questions and getting the same kinds of information to input 
into a system. 

One way to start is to see if we can make generalizations about the clients- 
expectations. Of course the clients are different, but sometimes they can have a lot 
in common. 



Consider these questions: 

♦ What kinds of systems are there? What are the system types? 

♦ What kinds of accounts are there? 

♦ What kind of customer requests are there? 

♦ If you had to give client profiles, what information would you include? 
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PROFILES 



Pick a client with whom you are familiar. Generate questions to get all the 
information required for the profile. Then write a profile of that client so that it 
follows the acceptable standard. Next, give a description of the account type and 
requests. 
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DOCUMENTATION ♦ SESSION 3 



OBJECTIVES: 

At the end of this session, students will be able to do the following: 

• identify problems with documentation 

• fix bad documentation 

• use clear editing abbreviations 



TOPICS: 



• unclear messages 

• incomplete instructions 

• fixing bad documentation 

• editing abbreviations 



METHODS: 



• class discussion 

• pair work 



EVALUATION: 



At the end of this session, students will be more competent in these areas: 

• recognizing poor documentation 

• writing clear documentation 

giving and taking clear instructions for rewriting poor documentation 



MATERIALS: 



worksheets 

examples of bad documentation 
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FIXING BAD DOCUMENTATION 



The Process By Which One Performs The Installation Technique 

The NorthTamCo Mailing List System can easily receive the installation technique 
performed by the user. 

By typing the directory name MD, create a DOS directory {Directory Name). 
Enter. Currently, the name you desire to be assigned to the directory would be 
keyed in the parenthesis. It is imperative that the name which is desired be a name 
that can be easily recognized by each and every alternative user. By typing CD, 
the directory can be changed by the user {Name of the Directory), where the name 
of the intended directory is the name of the newly created directory. Enter. The 
disk can be inserted. The diskette drive B should be employed for this particular 
aspect of the process. If not, another drive should be designated. (C = the drive 
the software is being installed on). Enter. The North System has at this point in 
time been successfully and completely installed. 
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FIXING BAD DOCUMENTATION 



Word for Windows File 



Turn on. Hit Microsoft Word. Insert disk. 
Click on file. Open. 



Hit OPEN file icon. Change drives. 
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FIXING BAD DOCUMENT A TION 



From the main screen, depress F9. An Export pop-up window should appear. At 
this juncture of events, the operator will be informed of the number, of diskettes 
required to export the records. Using the arrow key, the drive to which the records 
will be exported to will be selected. Press ENTER. A "Please Wait" pop-up 
window ought to appear. The process having been completed, the operator vvill be 
taken back to the main screen again. 



Note All records should have been previously loaded onto the selected drive. 
By depressing F10, the program will be excited from. 
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ABBREVIATIONS FOR EDITING 



Abbreviation 


Meaning 


A/P voice 


active / passive voice 


vb.t. 


verb tense 


pro. 


pronoun 


sbj. 


subject 


obj. 


object 


vb. 


verb 


agr. 


agreement 


sbj./vb. agr. 


subject / verb agreement 


sbj./ pro. agr. 


subject / pronoun agreement 


sing. 


singular 


pi. 


plural 


mod. 


modifier 


w.w. 


wrong word 


w.i. 


wrong information 


frag. 


fragment 


punct. 


punctuation 


sp. 


OMOl lift fl 

spelling 


inc. 


incomplete sentence 


e.g. 


example 


seq. 


sequence 


amb. 


ambiguous 


instr. 


instruction(s) 


unci. 


unclear 


r.o. 


run on sentence 
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STANDARD REVISION MARKS 



Mark 


Meaning 


Draft 


Revision 




inseit space 


It will take 
sometime to do. 


It will take 
some time to do. 




close up space 


Please finish this 
some time soon. 


Please finish this 
sometime soon. 




align vertically 


$4.77 
$5.78 
$86.53 


$4.77 
$5.78 
$86.53 




new paragraph 


Please get back 
to us this week. 


Please get back 
to us this week. 




indent 


Your materials 
are enclosed. 


Your materials 
are enclosed. 




use capital letters 


john spoke to 
mr. Lewis. 


John spoke to 
Mr. Lewis. 
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STANDARD REVISION MARKS 



Mark 


Meaning 


Draft 


Revision 




use lowercase 
letters 


We used the new 
Computers. 


We used the new 
computers. 




move to left 


The report was 
not on time. 


The report was 
not on time. 




move to right 


Denver 
Colorado 


Denver 
Colorado 




boldface print 


Proofreading is 
important. 


Proofreading is 

important. 




delete information 


Dave spoke toe 
the the group. 


Dave spoke to the 
group. 




insert information 


Maria went 
the meeting. 


Maria went to the 
meeting. 




transpose 


We will able be 
to make a profit. 


We will be able to 
make a profit. 




move 


On May 8, the 
company hired 
me. 


The company 
hired me on 
May 8. 
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DOCUMENTATION ♦ SESSION 4 



OBJECTIVES: 

At the end of this session, students will be able to do the following: 



identify problems with documentation 
fix bad documentation 
use clear editing abbreviations 
review previously discussed concepts 



TOPICS: 



elements of good vs. documentation 
fixing bad documentation 
using editing abbreviations 



METHODS: 



class discussion 
pair work 



EVALUATION: 

At the end of this session, students will be more competent in these areas: 



recognizing poor documentation 
writing clear documentation 

giving and taking clear instructions for rewriting poor documentation 



MATERIALS: 



example of bad documentation 



ERLC 
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USER DOCUMENT STRUCTURE 



When composing a User Document, please attend to the following outline: 

A. Cover Sheet 

♦ Client Name 

♦ Job Number 

♦ Client Contact 

♦ Data Coordinator 

♦ Sales Executive 

♦ Planner 

♦ Date Proposed 

B. Table of Contents 



C. Program Narrative 

♦ Background Information 

♦ Scope of Job (Marketing Objectives) 

D. System Profile 

♦ Mainframe Online 

♦ Mainframe Batch 

♦ PC - Development Software 



E. Input 

♦ Sources 

♦ Upfront Clerical Procedures 

♦ Disposition of Input 
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USER DOCUMENT STRUCTURE 



F. Operating Instruments 

♦ File Outputs 

♦ Detailed Walkthrough 

♦ Screens 

♦ Greensheets 

♦ Run Instructions 



G. Outputs 

♦ Types (names of reports and descriptions) 

♦ Quantity of copies 

♦ Frequency 

♦ Samples (when possible) 

H. Quality Assessment (QA) 

♦ Processes and Procedures 

♦ Check List 
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USER DOCUMENT STRUCTURE 

Note to Instructor: 

Use company specific User Documentation 
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DOCUMENTATION ♦ SESSION 5 



OBJECTIVES: 

At the end of this session, students will be able to do the following: 

• write their own clear and concise documentation 

TOPICS: 

• writing documentation 

METHODS: 

• individual writing 

EVALUATION: 

• students will evaluate their own work as they write 

MATERIALS: 

• self- generated 
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DOCUMENTATION ♦ SESSION 6 



OBJECTIVES: 

At the end of this session, students will be able to do the following: 

. . write their own clear and concise documentation 
• evaluate each other's work 



TOPICS: 



writing documentation 
peer evaluation 
documentation checklist 



METHODS: 



• individual writing 

• peer critique 



EVALUATION: 



students will evaluate their own work as they write 
students will evaluate each other's work when they have c 
their own documentation 



MATERIALS: 

• self-generated 



DOCUMENTA TION CHECKLIST 




Now that you have written your documentation, have you . . .? 

♦ Defined a clear purpose? 

♦ Identified your audience? 

♦ Kept a clear sequence? 

♦ Written in a clear and concise manner using 

• active voice? 

• strong and clear verbs? 

• consistent verb tenses? 

• correctly placed modifiers? 

• clear pronouns? 

• clear time words and other directives? 

• specific number amounts? 

♦ Avoided jargon and verbose structures? 

♦ Included appropriate visuals? 

♦ Included a cover sheet and profile? 



♦ Is your document user friendly? 

♦ Is your document easy to update? 
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